<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.14"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>emacps: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="HTML_custom.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="xlogo_bg.gif"/></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">emacps
   </div>
   <div id="projectbrief">Xilinx SDK Drivers API Documentation</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.14 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',false,false,'search.php','Search');
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('index.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">emacps Documentation</div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>The Xilinx Embedded Processor Block Ethernet driver. For a full description of XEMACPS features, please see the hardware spec. This driver supports the following features:</p><ul>
<li>Memory mapped access to host interface registers</li>
<li>Statistics counter registers for RMON/MIB</li>
<li>API for interrupt driven frame transfers for hardware configured DMA</li>
<li>Virtual memory support</li>
<li>Unicast, broadcast, and multicast receive address filtering</li>
<li>Full and half duplex operation</li>
<li>Automatic PAD &amp; FCS insertion and stripping</li>
<li>Flow control</li>
<li>Support up to four 48bit addresses</li>
<li>Address checking for four specific 48bit addresses</li>
<li>VLAN frame support</li>
<li>Pause frame support</li>
<li>Large frame support up to 1536 bytes</li>
<li>Checksum offload</li>
</ul>
<p><b>Driver Description</b></p>
<p>The device driver enables higher layer software (e.g., an application) to communicate to the XEmacPs. The driver handles transmission and reception of Ethernet frames, as well as configuration and control. No pre or post processing of frame data is performed. The driver does not validate the contents of an incoming frame in addition to what has already occurred in hardware. A single device driver can support multiple devices even when those devices have significantly different configurations.</p>
<p><b>Initialization &amp; Configuration</b></p>
<p>The <a class="el" href="struct_x_emac_ps___config.html" title="This typedef contains configuration information for a device. ">XEmacPs_Config</a> structure is used by the driver to configure itself. This configuration structure is typically created by the tool-chain based on hardware build properties.</p>
<p>The driver instance can be initialized in</p>
<ul>
<li>XEmacPs_CfgInitialize(InstancePtr, CfgPtr, EffectiveAddress): Uses a configuration structure provided by the caller. If running in a system with address translation, the provided virtual memory base address replaces the physical address present in the configuration structure.</li>
</ul>
<p>The device supports DMA only as current development plan. No FIFO mode is supported. The driver expects to start the DMA channels and expects that the user has set up the buffer descriptor lists.</p>
<p><b>Interrupts and Asynchronous Callbacks</b></p>
<p>The driver has no dependencies on the interrupt controller. When an interrupt occurs, the handler will perform a small amount of housekeeping work, determine the source of the interrupt, and call the appropriate callback function. All callbacks are registered by the user level application.</p>
<p><b>Virtual Memory</b></p>
<p>All virtual to physical memory mappings must occur prior to accessing the driver API.</p>
<p>For DMA transactions, user buffers supplied to the driver must be in terms of their physical address.</p>
<p><b>DMA</b></p>
<p>The DMA engine uses buffer descriptors (BDs) to describe Ethernet frames. These BDs are typically chained together into a list the hardware follows when transferring data in and out of the packet buffers. Each BD describes a memory region containing either a full or partial Ethernet packet.</p>
<p>Interrupt coalescing is not suppoted from this built-in DMA engine.</p>
<p>This API requires the user to understand how the DMA operates. The following paragraphs provide some explanation, but the user is encouraged to read documentation in <a class="el" href="xemacps__bdring_8h.html">xemacps_bdring.h</a> as well as study example code that accompanies this driver.</p>
<p>The API is designed to get BDs to and from the DMA engine in the most efficient means possible. The first step is to establish a memory region to contain all BDs for a specific channel. This is done with <a class="el" href="group__emacps__v3__1.html#ga8e84294f518be6f9089cbac00e924056" title="Using a memory segment allocated by the caller, create and setup the BD list for the given DMA channe...">XEmacPs_BdRingCreate()</a>. This function sets up a BD ring that hardware will follow as BDs are processed. The ring will consist of a user defined number of BDs which will all be partially initialized. For example on the transmit channel, the driver will initialize all BDs' so that they are configured for transmit. The more fields that can be permanently setup at initialization, then the fewer accesses will be needed to each BD while the DMA engine is in operation resulting in better throughput and CPU utilization. The best case initialization would require the user to set only a frame buffer address and length prior to submitting the BD to the engine.</p>
<p>BDs move through the engine with the help of functions <a class="el" href="group__emacps__v3__1.html#gabadbd5215bb371a7f10f8bd1acc2db38" title="Reserve locations in the BD list. ">XEmacPs_BdRingAlloc()</a>, <a class="el" href="group__emacps__v3__1.html#gacbfaf8300ce76fa1853ee9b1a113fbd0" title="Enqueue a set of BDs to hardware that were previously allocated by XEmacPs_BdRingAlloc(). ">XEmacPs_BdRingToHw()</a>, XEmacPs_BdRingFromHw(), and <a class="el" href="group__emacps__v3__1.html#gafef8904055a06754515319a708fc8361" title="Frees a set of BDs that had been previously retrieved with XEmacPs_BdRingFromHw(). ">XEmacPs_BdRingFree()</a>. All these functions handle BDs that are in place. That is, there are no copies of BDs kept anywhere and any BD the user interacts with is an actual BD from the same ring hardware accesses.</p>
<p>BDs in the ring go through a series of states as follows:</p><ol type="1">
<li>Idle. The driver controls BDs in this state.</li>
<li>The user has data to transfer. <a class="el" href="group__emacps__v3__1.html#gabadbd5215bb371a7f10f8bd1acc2db38" title="Reserve locations in the BD list. ">XEmacPs_BdRingAlloc()</a> is called to reserve BD(s). Once allocated, the user may setup the BD(s) with frame buffer address, length, and other attributes. The user controls BDs in this state.</li>
<li>The user submits BDs to the DMA engine with XEmacPs_BdRingToHw. BDs in this state are either waiting to be processed by hardware, are in process, or have been processed. The DMA engine controls BDs in this state.</li>
<li>Processed BDs are retrieved with XEmacEpv_BdRingFromHw() by the user. Once retrieved, the user can examine each BD for the outcome of the DMA transfer. The user controls BDs in this state. After examining the BDs the user calls <a class="el" href="group__emacps__v3__1.html#gafef8904055a06754515319a708fc8361" title="Frees a set of BDs that had been previously retrieved with XEmacPs_BdRingFromHw(). ">XEmacPs_BdRingFree()</a> which places the BDs back into state 1.</li>
</ol>
<p>Each of the four BD accessor functions operate on a set of BDs. A set is defined as a segment of the BD ring consisting of one or more BDs. The user views the set as a pointer to the first BD along with the number of BDs for that set. The set can be navigated by using macros XEmacPs_BdNext(). The user must exercise extreme caution when changing BDs in a set as there is nothing to prevent doing a mBdNext past the end of the set and modifying a BD out of bounds.</p>
<p><a class="el" href="group__emacps__v3__1.html#gabadbd5215bb371a7f10f8bd1acc2db38" title="Reserve locations in the BD list. ">XEmacPs_BdRingAlloc()</a> + <a class="el" href="group__emacps__v3__1.html#gacbfaf8300ce76fa1853ee9b1a113fbd0" title="Enqueue a set of BDs to hardware that were previously allocated by XEmacPs_BdRingAlloc(). ">XEmacPs_BdRingToHw()</a>, as well as XEmacPs_BdRingFromHw() + <a class="el" href="group__emacps__v3__1.html#gafef8904055a06754515319a708fc8361" title="Frees a set of BDs that had been previously retrieved with XEmacPs_BdRingFromHw(). ">XEmacPs_BdRingFree()</a> are designed to be used in tandem. The same BD set retrieved with BdRingAlloc should be the same one provided to hardware with BdRingToHw. Same goes with BdRingFromHw and BdRIngFree.</p>
<p><b>Alignment &amp; Data Cache Restrictions</b></p>
<p>Due to the design of the hardware, all RX buffers, BDs need to be 4-byte aligned. Please reference <a class="el" href="xemacps__bd_8h.html">xemacps_bd.h</a> for cache related macros.</p>
<p>DMA Tx:</p>
<ul>
<li>If frame buffers exist in cached memory, then they must be flushed prior to committing them to hardware.</li>
</ul>
<p>DMA Rx:</p>
<ul>
<li>If frame buffers exist in cached memory, then the cache must be invalidated for the memory region containing the frame prior to data access</li>
</ul>
<p>Both cache invalidate/flush are taken care of in driver code.</p>
<p><b>Buffer Copying</b></p>
<p>The driver is designed for a zero-copy buffer scheme. That is, the driver will not copy buffers. This avoids potential throughput bottlenecks within the driver. If byte copying is required, then the transfer will take longer to complete.</p>
<p><b>Checksum Offloading</b></p>
<p>The Embedded Processor Block Ethernet can be configured to perform IP, TCP and UDP checksum offloading in both receive and transmit directions.</p>
<p>IP packets contain a 16-bit checksum field, which is the 16-bit 1s complement of the 1s complement sum of all 16-bit words in the header. TCP and UDP packets contain a 16-bit checksum field, which is the 16-bit 1s complement of the 1s complement sum of all 16-bit words in the header, the data and a conceptual pseudo header.</p>
<p>To calculate these checksums in software requires each byte of the packet to be read. For TCP and UDP this can use a large amount of processing power. Offloading the checksum calculation to hardware can result in significant performance improvements.</p>
<p>The transmit checksum offload is only available to use DMA in packet buffer mode. This is because the complete frame to be transmitted must be read into the packet buffer memory before the checksum can be calculated and written to the header at the beginning of the frame.</p>
<p>For IP, TCP or UDP receive checksum offload to be useful, the operating system containing the protocol stack must be aware that this offload is available so that it can make use of the fact that the hardware has verified the checksum.</p>
<p>When receive checksum offloading is enabled in the hardware, the IP header checksum is checked, where the packet meets the following criteria:</p>
<ol type="1">
<li>If present, the VLAN header must be four octets long and the CFI bit must not be set.</li>
<li>Encapsulation must be RFC 894 Ethernet Type Encoding or RFC 1042 SNAP encoding.</li>
<li>IP v4 packet.</li>
<li>IP header is of a valid length.</li>
<li>Good IP header checksum.</li>
<li>No IP fragmentation.</li>
<li>TCP or UDP packet.</li>
</ol>
<p>When an IP, TCP or UDP frame is received, the receive buffer descriptor gives an indication if the hardware was able to verify the checksums. There is also an indication if the frame had SNAP encapsulation. These indication bits will replace the type ID match indication bits when the receive checksum offload is enabled.</p>
<p>If any of the checksums are verified incorrect by the hardware, the packet is discarded and the appropriate statistics counter incremented.</p>
<p><b>PHY Interfaces</b></p>
<p>RGMII 1.3 is the only interface supported.</p>
<p><b>Asserts</b></p>
<p>Asserts are used within all Xilinx drivers to enforce constraints on parameters. Asserts can be turned off on a system-wide basis by defining, at compile time, the NDEBUG identifier. By default, asserts are turned on and it is recommended that users leave asserts on during development. For deployment use -DNDEBUG compiler switch to remove assert code.</p>
<dl class="section note"><dt>Note</dt><dd></dd></dl>
<p>Xilinx drivers are typically composed of two parts, one is the driver and the other is the adapter. The driver is independent of OS and processor and is intended to be highly portable. The adapter is OS-specific and facilitates communication between the driver and an OS. This driver is intended to be RTOS and processor independent. Any needs for dynamic memory management, threads or thread mutual exclusion, or cache control must be satisfied bythe layer above this driver.</p>
<pre>
 MODIFICATION HISTORY:</pre><pre> Ver   Who  Date     Changes
<hr/>

 1.00a wsy  01/10/10 First release
 1.00a asa  11/21/11 The function XEmacPs_BdRingFromHwTx in file
                       <a class="el" href="xemacps__bdring_8c.html">xemacps_bdring.c</a> is modified. Earlier it was checking for
                       "BdLimit"(passed argument) number of BDs for finding out
                       which BDs are successfully processed. Now one more check
                       is added. It looks for BDs till the current BD pointer
                       reaches HwTail. By doing this processing time is saved.
 1.00a asa  01/24/12 The function XEmacPs_BdRingFromHwTx in file
                       <a class="el" href="xemacps__bdring_8c.html">xemacps_bdring.c</a> is modified. Now start of packet is
                       searched for returning the number of BDs processed.
 1.02a asa  11/05/12 Added a new API for deleting an entry from the HASH
                       registers. Added a new API to set the bust length.
                       Added some new hash-defines.
 1.03a asa  01/23/12 Fix for CR #692702 which updates error handling for
                       Rx errors. Under heavy Rx traffic, there will be a large
                       number of errors related to receive buffer not available.
                       Because of a HW bug (SI #692601), under such heavy errors,
                       the Rx data path can become unresponsive. To reduce the
                       probabilities for hitting this HW bug, the SW writes to
                       bit 18 to flush a packet from Rx DPRAM immediately. The
                       changes for it are done in the function
                       XEmacPs_IntrHandler.
 1.05a asa  09/23/13 Cache operations on BDs are not required and hence
                       removed. It is expected that all BDs are allocated in
                       from uncached area.
 1.06a asa  11/02/13 Changed the value for XEMACPS_RXBUF_LEN_MASK from 0x3fff
                                to 0x1fff. This fixes the CR#744902.
                          Made changes in example file <a class="el" href="xemacps__example_8h.html" title="Defines common data types, prototypes, and includes the proper headers for use with the EMACPS exampl...">xemacps_example.h</a> to fix compilation
                          issues with iarcc compiler.
 2.0   adk  10/12/13 Updated as per the New Tcl API's
 2.1   adk  11/08/14 Fixed the CR#811288. Changes are made in the driver tcl file.
 2.1   bss  09/08/14 Modified driver tcl to fix CR#820349 to export phy
                       address in xparameters.h when GMII to RGMII converter
                       is present in hw.
 2.1   srt  07/15/14 Add support for Zynq Ultrascale Mp GEM specification and 64-bit
                       changes.
 2.2   adk  29/10/14 Fixed CR#827686 when PCS/PMA core is configured with
                    1000BASE-X mode export proper values to the xparameters.h
                    file. Changes are made in the driver tcl file.
 3.0   adk  08/1/15  Don't include gem in peripheral test when gem is
                    configured with PCS/PMA Core. Changes are made in the
                       test app tcl(CR:827686).
 3.0   kvn  02/13/15 Modified code for MISRA-C:2012 compliance.
 3.0   hk   03/18/15 Added support for jumbo frames. Increase AHB burst.
                     Disable extended mode. Perform all 64 bit changes under
                     check for arch64.
                     Remove "used bit set" from TX error interrupt masks.
 3.1   hk   07/27/15 Do not call error handler with '0' error code when
                     there is no error. CR# 869403
            08/10/15 Update upper 32 bit tx and rx queue ptr registers.
 3.2   hk   02/22/16 Added SGMII support for Zynq Ultrascale+ MPSoC.
 3.4   ms   01/23/17 Modified xil_printf statement in main function for all
                     examples to ensure that "Successfully ran" and "Failed"
                     strings are available in all examples. This is a fix
                     for CR-965028.
       ms   03/17/17 Modified text file in examples folder for doxygen
                     generation.
 </pre> </div></div><!-- contents -->
</div><!-- doc-content -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Copyright &copy; 2015 Xilinx Inc. All rights reserved.</li>
  </ul>
</div>
</body>
</html>
